Add repeatable marketing screenshot generation - #4508

Related issues

• None.

How AI was used in this PR

This proof of concept was designed, implemented, exercised, and documented with Codex. Human
direction established the marketing goals and corrected the key fidelity requirements: a populated
demo portfolio, narrow chat and wide preview layouts, controllable panels and composers, real
WordPress/phpMyAdmin surfaces, and saved screenshots that match the visible Electron window.

Codex inspected the Agentic UI and Studio CLI, built both capture tiers, created the isolated-site
harness, ran the complete catalog and annotation flows in light and dark, visually reviewed the
outputs, and prepared this review guide. Reviewers should validate the architecture, scenario
content, privacy boundary, and visual choices rather than treating an AI-assisted proof of concept
as merge-ready by default.

Executive summary

This draft adds a repeatable system for generating Studio Agentic UI screenshots for landing pages,
documentation, app stores, Pressable, Automattic for Agencies, and similar marketing surfaces.

There is now one demo site: a checked-in Meridian Coffee WordPress block theme installed into a
fresh temporary Studio site for every run. There is no static frontend replacement. The two capture
tiers differ only in how Studio is hosted:

• Browser renderer tier: fast Chromium matrices of production React components and curated
  Studio scenario data. Preview-capable scenarios load the real WordPress site through Studio's
  normal <iframe> fallback.
• Electron annotation tier: a capture-only Electron window that loads the same site through the
  real <webview> and exercises the actual annotation inspector, WP Admin, and phpMyAdmin.

Both tiers write exact-size PNGs, a manifest, and a standalone contact sheet into ignored artifact
directories. Electron output uses BrowserWindow.webContents.capturePage() because a Playwright
host-page screenshot can mis-scale or crop the separately composited <webview> even while the
visible window is correct.

Example output

Complete renderer catalog — real WordPress preview

Twenty 2880 × 1800 captures cover all ten scenarios in light and dark. Every visible Meridian
preview in this sheet came from the same isolated WordPress block theme used by Electron.

Real WordPress annotation flow

Annotation draft · light The real inspector is attached to the real WordPress theme heading.	Annotation submitted · dark The annotation crosses the guest/host bridge and appears in the Studio conversation.
WordPress tab · real WP 7.0.4 The runner asserts the genuine wp-admin DOM before saving the PNG.	Database tab · real phpMyAdmin The runner asserts phpMyAdmin and shows the temporary site's actual wp_* tables.

Proposed Changes

• Gives marketing and documentation teams a repeatable way to render ten Agentic UI scenarios at
  controllable sizes, themes, panel layouts, composer states, and conversation positions.
• Uses one standardized, isolated Meridian Coffee WordPress site across browser and Electron
  captures so the demo design cannot drift between two implementations.
• Keeps the surrounding portfolio, conversations, and connected-site state curated and
  deterministic without reading personal Studio data or invoking a live model.
• Captures the complete annotation flow plus genuine WordPress and Database tabs from an isolated
  Electron window.
• Validates readiness, allowed network origins, images, exact PNG dimensions, native display scale,
  Fit-pane guest/host geometry, frontend overflow, and genuine WP Admin/phpMyAdmin DOM markers.
• Produces ignored manifests and standalone contact sheets for review and downstream handoff.

Agent-first workflow

The intended workflow is for a marketer or engineer to describe the required compositions and let
an agent perform checkout, build, capture, inspection, iteration, and handoff.

A useful prompt is:

Check out the add-marketing-screenshot-system branch and read
tools/marketing-screenshots/README.md. Generate the requested Studio marketing screenshots.
Require the automatically provisioned Meridian WordPress site for every preview—never personal
sites or handcrafted substitute HTML. Use the native command for annotations, WordPress, or
Database tabs. Capture light and dark unless told otherwise, inspect the contact sheet and
full-size PNGs, report diagnostics, and copy only approved output to the requested destination.

The agent should:

1. Check out the branch and install dependencies.
2. Run the build-and-capture command so output reflects the current checkout.
3. Open contact-sheet.html and inspect the full-size PNGs in both themes.
4. Confirm the manifest is clean and the selected layout and conversation states are correct.
5. For native output, confirm the genuine WP/phpMyAdmin and Fit-pane geometry assertions pass.
6. Iterate through supported capture inputs or the checked-in theme/scenario content; never patch a
   screenshot or create replacement site/admin/database HTML.
7. Copy approved PNGs to the delivery location while leaving bulk output out of Git.

Checkout, build, and use

git fetch origin add-marketing-screenshot-system
git switch --create add-marketing-screenshot-system --track origin/add-marketing-screenshot-system
npm install

Generate the default browser-renderer set:

npm run screenshots:marketing

Generate the complete wide renderer catalog:

npm run screenshots:marketing -- \
  --scenario all \
  --theme all \
  --preset raw-wide-2x \
  --output artifacts/marketing-screenshots/catalog

Generate the real annotation flow:

npm run screenshots:marketing:native -- \
  --theme light \
  --preset raw-wide-2x \
  --output artifacts/marketing-screenshots/annotation-flow/light

Repeat with --theme dark for the paired dark set. Once both builds are current, use the
corresponding :capture command for faster iteration. Each invocation still creates and destroys a
fresh real WordPress site.

How it works

1. The command builds the Studio CLI and marketing-only Agentic UI target.
2. The built CLI creates a real sandbox WordPress + SQLite site in isolated temporary directories
   and activates the checked-in Meridian Marketing block theme.
3. A named scenario loads production React components through a deterministic marketing connector,
   pointing its selected site at the temporary WordPress origin.
4. Chromium captures general scenario matrices through the real iframe preview; Electron captures
   annotation/admin/database states through the real webview.
5. Explicit readiness and semantic controls avoid fixed-coordinate scripting. Electron uses
   composed-window capture for correct guest pixels.
6. The runner writes exact-size images, diagnostics, a manifest, and a contact sheet, then stops the
   isolated daemon and removes the temporary site and configuration.

Review guide

Please review carefully:

• Whether an in-repository capture tool is the right ownership boundary for this source-coupled
  workflow.
• Whether the marketing-only connector is an acceptable way to represent curated Studio states
  while the selected site itself remains real.
• Whether one automatically provisioned block theme is the right fidelity/repeatability tradeoff
  for every preview capture.
• Whether the capturePage() rule and DOM/geometry assertions adequately prevent recurrence of the
  scaled/cropped Electron output.
• Whether the scenario names, content, and compositions represent Studio accurately.
• Whether the commands and guardrails are clear enough for agent-driven refreshes.

Okay to skim

• The Meridian block-template presentation markup after confirming its generated real-site pixels.
• Individual curated conversation entries after their visible claims are approved.
• Manifest and contact-sheet HTML generation covered by focused tests.

Known tradeoffs and follow-ups

• The Electron tier captures correctly composed BrowserWindow content on macOS, but it does not yet
  prove a packaged app's external OS shadow/chrome. Matching Windows and Linux hosts remain separate
  fidelity work.
• The selected site is real WordPress; the surrounding marketing portfolio and conversations remain
  deterministic scenario data, and no live model run occurs.
• Provisioning WordPress makes broad browser matrices slower than static HTML did, but removes a
  second demo implementation and keeps all publishable preview pixels honest.
• This draft does not publish to a DAM or run captures in CI.
• Full workspace typecheck currently encounters an existing duplicate incompatible ignore package
  type mismatch in apps/studio/src/ipc-handlers.ts; the affected focused typechecks pass.

Safety checklist

• No personal Studio configuration, saved site list, authentication, or ~/Studio site is read.
• CLI config, process manager, site files, app data, and native Electron user data are isolated.
• The daemon is stopped and temporary directories are removed after every run.
• Static frontend, WP Admin, and phpMyAdmin substitutes are absent.
• Real WP Admin and phpMyAdmin DOM assertions run before native capture.
• Generated review media is stored on the PR upload ref, not the feature branch.
• Existing user flows and persisted data are unchanged; this is opt-in tooling.
• Packaged-app and per-OS chrome fidelity remain follow-up work.

Testing Instructions

Focused validation completed:

npx eslint --fix <modified TypeScript and React files>
npx tsc -p tools/marketing-screenshots/tsconfig.json --noEmit
npm -w @studio/ui run typecheck
npx vitest run --config tools/marketing-screenshots/vitest.config.ts
npm test -- apps/ui/src/marketing/index.test.ts apps/ui/src/components/site-preview/index.test.tsx
node --experimental-strip-types tools/marketing-screenshots/capture.ts \
  --scenario all --theme all --preset raw-wide-2x --output <renderer-output>
node --experimental-strip-types tools/marketing-screenshots/native-capture.ts \
  --theme light --preset raw-wide-2x --output <native-light-output>
node --experimental-strip-types tools/marketing-screenshots/native-capture.ts \
  --theme dark --preset raw-wide-2x --output <native-dark-output>
git diff --check

Results:

• Screenshot runner tests: 27 passed.
• Agentic UI marketing tests: 14 passed.
• Focused screenshot-tool and Agentic UI typechecks passed.
• Current CLI and marketing UI builds passed.
• The complete renderer run produced twenty real-preview 2880 × 1800 PNGs across ten scenarios and
  both Studio themes.
• Real light and dark annotation runs each produced seven 2880 × 1800 PNGs plus a manifest/contact
  sheet.
• Visual review covered browser previews, the hero-heading annotation flow, submitted conversation
  state, genuine WordPress 7.0.4 WP Admin, genuine phpMyAdmin tables, and both Studio themes.

Pre-merge Checklist

• Checked the marketing target for TypeScript, React, browser console, page, request, image,
  readiness, and PNG-dimension errors.
• Verified browser and native outputs in light and dark themes.
• Kept personal data and generated bulk output out of the commit.
• Uploaded current review-only images through the PR upload ref.
• Resolve or independently confirm the existing full-workspace ignore package type mismatch.
• Agree on long-term architecture, ownership, and content direction for this proof of concept.